lslportalfandomcom-20200213-history
LSL Comments
What are Comments? Programming code needs to be written in a way, the compiler for a programming language understands. This so-called source-code, should be written to be easy and understandable. The Source code is self-commenting, when the variable names describe their usage and the code is formatted and written in a way, to be easy readable, so someone can understand what it is doing. Still, this is not always sufficient. So we need a way to write regular language within source code, to explain things further. That's the reason why every programming language, and LSL is no exception, provides a method to write comments. : A Comment is text, that is completely ignored from the compiler. They don't have any function in the executed code and it doesn't matter for the compiler, if comments exist or not. Comments are for us humans. Best practices for comments Comments are used for a variety of reasons: *Explaining better what the code does *Mentioning Reasons for why one method is used over another *To document values passed in, how functions should be used or what return values contain *To "comment out" a line or section of code, that should not be executed for some reason, but the coder has a reason to not remove it completely, as example when testing alternatives *To add several information about the author, copyrights, licenses etc. : The frequency of comments sometimes reflects the poor quality of code. When you feel compelled to add too many comments, consider rewriting the code to make it clearer. No comments at all are not good, but too many comments make code less readable too. Good practices are, to avoid comments that can become too fast out-of-date as the code evolves, comments that are redundant, duplicate information as also what is clear from the code. Avoid to use fancy formatting or special characters in comments. Syntax of Comments In general, programming languages have a different set of comment syntax, including single-line comments, block comments, end-of-line comments and documentation comments - though the syntax for those comments is sometimes similar. LSL knows from all those the end-of-line comments in all LSL versions and viewers. Block comments are available in the Mono Engine and in newer versions of the SL viewer for the LSO Engine. : End-of-line (//) and single-line comments (/* */) are sometimes confused and the second term used instead of the first, but they are not the same. Older SL viewers can compile only End-of-line comments in the LSO Engine and will give a syntax error for block and single-line comments. End-of-line Comments End-of-line comments begin with double forward slashes (//) and end with the end of the line. It can comment out a whole line or partially, but always until the next line. To comment out multiple consecutive lines, the block comment syntax should be used instead. Some examples of valid and invalid end-of-line comments Single-line / Trailing Comments Those comments start with /* and end with */. They should appear intended with code, either on their own line or at the end of a line that contains code. It is possible to comment out a partial part of a line with this syntax, but this is not suggested. Like in the example following, instead of commenting out a part of code, you should prefer to comment out the whole line and write the modified code on it's own line, as it makes code easier readable and maintainable like that. : The syntax here described has the same syntax as block comments. The compiler itself doesn't distinguish between those comments, it is more a declarative difference used generally from professional programmers. Block comments Block comments are used to comment out more then one line. Before block comments was introduced for LSL, the only method was to use the end-of-line comments. Though it is still a valid syntax, professional programmers use this syntax instead to comment out blocks. It is good coding style, to precede a block comment by a blank line to set it apart from the rest of code, though it's not required from the compiler. When large parts of code are commented out with block comments, it is easy to get confused. It should taken care to make it clear, what is a comment and what not. See the following examples for that.